Upgrade your checkout integration

UpgradeBeta

Last updated: Jul 1st, 1:53pm

If you have an Express Checkout integration, PayPal recommends upgrading to PayPal Checkout using the JavaScript SDK. The JavaScript SDK has the following benefits:

Dynamically renders payment buttons instead of using static images.

Launches payment flow in a pop-up window instead of redirecting to a new page.

Supports greater control over payment button styles.

Visit the Eligibility Page to learn more about the countries, currencies, and card brands that PayPal Checkout supports.

If your current integration is Express Checkout, you must upgrade to PayPal Checkout. You can use your site’s branding with PayPal Checkout, allowing customers to pay with PayPal, Pay Later options, Venmo, and alternative payment methods.

1. Review your current integration

1. Identify core API calls

Locate the endpoint URLs in your code that manage starting, reviewing, and completing paymetns. Check the API requests for the following METHOD parameter values:

SetExpressCheckout, GetExpressCheckoutDetails, DoExpressCheckoutPayment

2. Document parameters

Review the core API calls from your current integration and make a list of the parameters, such as PAYMENTREQUEST_0_AMT.

3. Parameter mapping tool

Map these parameters to the new API using our parameter mapping tool in our PayPal API Transformer.

2. Setup your sandbox

Sign in to your developer account

If you don't already have one, sign up for a PayPal developer account.

Get your sandbox credentials

Follow this onboarding document to get a client ID and secret, access token, and your sandbox account credentials.

Client ID: Authenticates your account with PayPal and identifies an app in your sandbox.

Client secret: Authorizes an app in your sandobx. Keep this secret safe and don't share it.

Access token: Authenticates your app when calling PayPal REST APIs.

Set up your sandbox account

Follow this account configuration document to set up your sandbox account and test purchases before going live in your live account.

Select Create App.

Input App Name, and under Type, select Merchant.

Click Create App.

Set up your front end to use PayPal payment buttons in PayPal Checkout. Select your upgrade path: choose 'For NVP/SOAP API-only integration' if you currently have an API-only integration, or choose 'For NVP/SOAP API and JavaScript SDK v4' if you're currently using checkout.js.

For NVP/SOAP API-only integration

Integrate PayPal's latest JavaScript SDK

PayPal's JavaScript SDK supports how you want to accept payments on your website. Our SDK handles displaying the buttons for PayPal and other payment methods, so your customers can pay with whatever method they choose. See Getting started for more information.

1. Follow steps 1-5 in the Integrate PayPal Checkout guide to set up and customize your PayPal payment buttons with JavaScript SDK v5.

Enable PayPal Checkout Payments

Upgraded

1<!DOCTYPE html>
2<html>
3    <head>
4        <meta charset="UTF-8" />
5        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6        <title>PayPal JS SDK PayPal Checkout Integration</title>
7    </head>
8    <body>
9        <div id="paypal-button-container"></div>
10        <p id="result-message"></p>
11
12       
13        <!-- Initialize the JS-SDK -->
14        <script
15            src="https://www.paypal.com/sdk/js?client-id=test&buyer-country=US&currency=USD&components=buttons&enable-funding=venmo,paylater,card"
16            data-sdk-integration-source="developer-studio"
17        ></script>
18        <script src="app.js"></script>
19       
20    </body>
21</html>
22

For NVP/SOAP API and JavaScript SDK v4

Upgrade your legacy JavaScript from v4 to v5

If you are using a previous version of PayPal's JavascriptSDK (checkout.js), upgrade your SDK to access the full rnage of features offered by PayPal Checkout.

1. Follow this guide to upgrade your SDK to the most recent version.

Legacy Express Checkout Button

Deprecated

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <title>PayPal Express Checkout (legacy checkout.js)</title>
6  <script src="https://www.paypalobjects.com/api/checkout.js"></script>
7</head>
8<body>
9  <div id="paypal-button-container"></div>
10
11  <script>
12    paypal.Button.render({
13      env: 'sandbox', // or 'production'
14
15      client: {
16        sandbox:    'YOUR_SANDBOX_CLIENT_ID',
17        production: 'YOUR_PRODUCTION_CLIENT_ID'
18      },
19
20      commit: true, // Show "Pay Now"
21
22      payment: function(data, actions) {
23        // Create payment on client side (or call your server)
24        return actions.payment.create({
25          payment: {
26            transactions: [{
27              amount: { total: '10.00', currency: 'USD' },
28              description: 'Order #12345 - Test payment'
29            }],
30            note_to_payer: 'Contact us for any questions.'
31          }
32        });
33      },
34
35      onAuthorize: function(data, actions) {
36        // Execute payment after customer approves
37        return actions.payment.execute().then(function(paymentDetails) {
38          console.log('Payment completed!', paymentDetails);
39          alert('Payment complete! Transaction ID: ' + paymentDetails.id);
40          // Typically, you'd send paymentDetails.id to your server here
41        });
42      },
43
44      onCancel: function(data) {
45        console.log('Payment cancelled', data);
46        alert('Payment cancelled.');
47      },
48
49      onError: function(err) {
50        console.error('Error during checkout', err);
51        alert('An error occurred: ' + err);
52      }
53    }, '#paypal-button-container');
54  </script>
55</body>
56</html>
57

Enable PayPal Checkout Payments

Upgraded

1<!DOCTYPE html>
2<html>
3    <head>
4        <meta charset="UTF-8" />
5        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6        <title>PayPal JS SDK PayPal Checkout Integration</title>
7    </head>
8    <body>
9        <div id="paypal-button-container"></div>
10        <p id="result-message"></p>
11
12       
13        <!-- Initialize the JS-SDK -->
14        <script
15            src="https://www.paypal.com/sdk/js?client-id=test&buyer-country=US&currency=USD&components=buttons&enable-funding=venmo,paylater,card"
16            data-sdk-integration-source="developer-studio"
17        ></script>
18        <script src="app.js"></script>
19       
20    </body>
21</html>
22

If you have an Express Checkout integration, you must set up server-side processing. You'll need to generate an access token, upgrade your NVP/SOAP API integraiton to the Orders v2 API, and set up a listener to handle API responses.

Generate access token

The NVP/SOAP API handles authentication using API credentials, such as, USER, PWD and SIGNATURE. These credentials are passed directly in the request.

In contrast, the Orders v2 REST API uses OAuth 2.0 for authentication, which requires an access token. To generate an access token:

Declare a generateAccessToken() function that makes a POST call to the /v1/oauth2/ token endpoint to create an access token.

Set up an auth parameter to combgine the PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET as a key-value pair.

Establish a data object that captures the response.json data from the request and returns the access_token.

This example shows a generateAccessToken() function:

generateAccessToken()

Upgraded

1<script>
2    const PAYPAL_CLIENT_ID = 'YOUR_CLIENT_ID';
3    const PAYPAL_CLIENT_SECRET = 'YOUR_CLIENT_SECRET';
4    const BASE_URL = 'https://api-m.sandbox.paypal.com';
5
6    async function generateAccessToken() {
7      const auth = btoa(`${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}`);
8      const response = await fetch(`${BASE_URL}/v1/oauth2/token`, {
9        method: 'POST',
10        headers: {
11          'Authorization': `Basic ${auth}`,
12          'Content-Type': 'application/x-www-form-urlencoded'
13        },
14        body: 'grant_type=client_credentials'
15      });
16
17      const data = await response.json();
18      if (!response.ok) {
19        const msg = data.error_description || JSON.stringify(data);
20        throw new Error(`Token request failed: ${msg}`);
21      }
22      return data.access_token;
23    }
24
25    async function onGetTokenClick() {
26      try {
27        const token = await generateAccessToken();
28        document.getElementById('result').textContent =
29          `Access Token:\n${token}`;
30      } catch (err) {
31        document.getElementById('result').textContent =
32          `Error generating token:\n${err.message}`;
33      }
34    }
35
36    document.getElementById('get-token')
37      .addEventListener('click', onGetTokenClick);
38</script>

Upgrade your NVP/SOAP API integration to REST APIs

Use the Orders v2 API to create, update, retrieve, authorize, and capture orders. Use the Payments v2 API for post-payment actions. The following table shows how a one-time payment request in NVP/SOAP API maps to a PayPal Checkout request in the Orders v2 REST API:

NVP/SOAP API	Orders v2 REST API
METHOD=SetExpressCheckout	POST /v2/checkout/orders
METHOD=GetExpressCheckoutDetails	GET /v2/checkout/orders/{order_id}
METHOD=DoExpressCheckoutPayment	POST /v2/checkout/orders/{order_id}/capture

To help you construct the request body to support the Orders v2 format, copy and paste your NVP/SOAP reqeuset body into our API Transformer tool.

Changing order details between request and capture

THe NVP/SOAP integration uses the DoExpressCheckoutAPI to process both order updates and capture order requests. When you need to change the order details, such as the address or amount, after your original SetExpressCheckout call, you can make a single DoExpressCheckout call to simultaneously change the order details and capture the payment.

To change the order details between request and capture using PayPal Checkout, you need to make 2 calls to the Orders v2 API: an Update order PATCH request to update the order, and a Capture payment for order request to finalize the checkout flow.

Example payloads

The following are examples of NVP/SOAP API request payloads and how they map to and PayPal Checkout request in the Orders v2 REST API:

1. SetExpressCheckout to CreateOrder

NVP Request

Deprecated

1paymentrequest_0_invnum=2025619101051
2&method=SetExpressCheckout
3&signature=PII
4&maxamt=2.00
5&version=204
6&returnurl=http://mywesbite.com/return
7&pwd=PII
8&cancelurl=http://mywebsite.com/cancel
9&user=PII
10&paymenttype=Any

PayPal Checkout REST API Request

Upgraded

1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer {AUTHORIZATION TOKEN}' \
4-d '{
5  "intent": "CAPTURE",
6  "purchase_units": [
7    {
8      "invoice_id": "2025619101051"
9    }
10  ],
11  "payment_source": {
12    "paypal": {
13      "experience_context": {
14        "return_url": "https://mywebsite.com/return",
15        "cancel_url": "https://mywebsite.com/cancel"
16      }
17    }
18  },
19  "final_capture": false
20}'

2. GetExpressCheckout to GetOrderDetails

NVP Request

Deprecated

1method=GetExpressCheckoutDetails
2&signature=xxxxxxxxx
3&pwd=xxxxxx
4&version=204
5&user=xxxxxxx
6&token=EC-9HU16110600994149
7
8
9
10

PayPal Checkout REST API request

Upgraded

1curl  https://api-m.sandbox.paypal.com/v2/checkout/orders/{id} \
2-H 'Content-Type: application/json' \
3-H 'Authorization: Bearer {AUTHORIZATION TOKEN}'
4
5
6
7
8
9
10

3. DoExpressCheckout to CaptureOrder

NVP Request

Deprecated

1USER=xxxxxxxx
2&PWD=xxxxxxxx
3&SIGNATURE=xxxxx
4&METHOD=DoExpressCheckoutPayments
5&VERSION=124.0
6&TOKEN=EC-72D0681527109671C
7&PAYMENTREQUEST_0_PAYMENTACTION=Sale
8&PAYMENTREQUEST_0_AMT=111.11
9
10

PayPal Checkout REST API request

Upgraded

1curl -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/2HX49812L18884342/capture' \
2-H 'Content-Type: application/json' \
3-H 'Prefer: return=representation' \
4-H 'Authorization: Bearer bearer_access_token'
5
6
7
8
9
10

Handle responses

Create a handleResponse function to set up a listener that returns an HTTP status code from the API response.

Set up handleResponse function to make a POST call to the /api/orders endpoint and return an HTTP status code response.

Declare an errorMessage object to show an error message when handleResponse returns an error code.

For more information about Orders V2 error scenarios, see OrdersV2 Error Messages page.

This example shows a handleResponse() function:

handleResponse()

Upgraded

1async function handleResponse(response){
2    try {
3        const jsonResponse = await resonse.json();
4        return {
5            jsonResponse,
6            httpStatusCode: response.status,
7        };
8    } catch (err) {
9      const errorMessage = await response.text();
10      throw new Error(errorMessage);
11    }
12}

Upgrade IPNs to Webhooks

Replace IPN(Instant Payment Notification) to webhooks for asynchronous event processing.

Create Endpoint: Build a secure HTTP POST endpoint (e.g., /webhook) to receive events.

Register URL: In your PayPal Developer Dashboard, add your webhook URL and select desired events (e.g., PAYMENT.CAPTURE.COMPLETED).

Validate Signatures: Implement signature verification to confirm events come from PayPal.

Update Logic: Replace IPN processing with webhook event handling in your code (e.g., update order status on PAYMENT.CAPTURE.COMPLETED).

Test Sandbox: Simulate events in the sandbox to ensure your endpoint handles notifications correctly.

Go Live: Update your live PayPal settings with your production URL and monitor logs for real-time event processing.

Fine-tune your experience

See the Orders v2 API reference to configure the details of your integration.

Before going live, test your integration in the sandbox environment. Learn more about card testing, simulating successful payments using test card numbers and generating card error scenarios using rejection triggers.

Note: Use the credit card generator to generate test credit cards for sandbox testing.

PayPal Payment

Select the PayPal button on your checkout page.

Log in using one of your personal sandbox accounts. This ensures the payments will be sent to the correct account.  Make sure that you use the sandbox business account that corresponds to the REST app you are using

Note the purchase amount in the PayPal checkout window.

Approve the purchase with the Pay Now button. The PayPal window closes and redirects you to your page,  indicating that the transaction was completed.

Confirm the money reached the business account:

Log in to the PayPal sandbox using the sandbox business account that received the payment. Remember that the SDK source now uses a  sandbox client ID from one of your REST apps, and not the default test ID.

In Recent Activity, confirm that the sandbox business account received the money, subtracting any fees.

Log out of the account.

Card payment

Go to the checkout page for your integration

Generate a test card using the credit card generator.

Enter the card details in the hosted field, including the name on the card, billing address, and 2-character country code. Then, submit the order.

Confirm that the order was processed.

Log in to your merchant sandbox account and navigate to the activity page to ensure the payment amount shows up in the account.

Follow this checklist to take your application live:

Log into the PayPal Developer Dashboard with your PayPal business account.

Obtain your live credentials.

Include the new credentials in your integration and Update your PayPal endpoint.

See Move your app to production for more details

Upgrade your checkout integration

Get Started

1. Review your current integration

1. Identify core API calls

2. Document parameters

3. Parameter mapping tool

2. Setup your sandbox

Sign in to your developer account

Get your sandbox credentials

Set up your sandbox account

Update your front end

For NVP/SOAP API-only integration

Integrate PayPal's latest JavaScript SDK

For NVP/SOAP API and JavaScript SDK v4

Upgrade your legacy JavaScript from v4 to v5

Configure the checkout experience

Generate access token

Upgrade your NVP/SOAP API integration to REST APIs

Changing order details between request and capture

Example payloads

1. SetExpressCheckout to CreateOrder

2. GetExpressCheckout to GetOrderDetails

3. DoExpressCheckout to CaptureOrder

Handle responses

Upgrade IPNs to Webhooks

Fine-tune your experience

Test the Integration

PayPal Payment

Confirm the money reached the business account:

Card payment

Go Live

Upgrade your checkout integration

Get Started

1. Review your current integration

1. Identify core API calls

2. Document parameters

3. Parameter mapping tool

2. Setup your sandbox

Sign in to your developer account

Get your sandbox credentials

Set up your sandbox account

Update your front end

For NVP/SOAP API-only integration

Integrate PayPal's latest JavaScript SDK

For NVP/SOAP API and JavaScript SDK v4

Upgrade your legacy JavaScript from v4 to v5

Configure the checkout experience

Generate access token

Upgrade your NVP/SOAP API integration to REST APIs

Changing order details between request and capture

Example payloads

1. SetExpressCheckout to CreateOrder

2. GetExpressCheckout to GetOrderDetails

3. DoExpressCheckout to CaptureOrder

Handle responses

Upgrade IPNs to Webhooks

Fine-tune your experience

Test the Integration

PayPal Payment

Confirm the money reached the business account:

Card payment

Go Live

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more